FirstSpirit is used for creating versatile and project-specific content. Thanks to ContentConnect, it is now possible to transfer this content to the Salesforce Commerce Cloud e-commerce shop system and use it there.
|
In the remainder of this document, the abbreviated form "Commerce Cloud" will be used instead of "Salesforce Commerce Cloud". This abbreviated form refers to Salesforce Commerce Cloud in all cases. |
ContentConnect combines the functional strengths of both systems, delivering the key advantages that each offers and creating a highly effective overall system made up of two areas that work in parallel and are largely decoupled from one another:
|
This document only deals with the FirstSpirit components. It assumes that the reader is familiar with Commerce Cloud and is able to use it competently. |
ContentConnect allows editors to:
Open Commerce API (OC API)
WebDAV
The corresponding functions are made available in both SiteArchitect and ContentCreator when the modules are installed and configured.
Familiar FirstSpirit tools are used to maintain the content, meaning that editors who are already familiar with FirstSpirit do not require any additional knowledge. The content is made available to Commerce Cloud as part of a deployment so that it can be imported. Commerce Cloud then transfers the information to the live state.
This means that there is no difference in the delivery process as far as Commerce Cloud is concerned, and that the delivery process is not dependent on the ability to access the FirstSpirit Server. Even if the FirstSpirit Server is shut down for maintenance work, for example, Commerce Cloud and, therefore, the deployed content delivery remain unaffected.
FirstSpirit and Commerce Cloud are linked by an architecture made up of a range of components (see figure Architecture). These components are:
The modules installed on the FirstSpirit Server:
The individual components always interact in accordance with the following schema:
http to FirstSpirit, where it is required in order to display the preview in full. Products are transferred to FirstSpirit via the OC API interface of the Commerce Cloud Staging instance.
WebDAV as part of a deployment. They are stored in various WebDAV directories in the form of media and XML files. From this point, they are then imported into the Commerce Cloud Staging instance library by means of jobs.
Commerce Cloud thus represents the main component in this architecture. It delivers the content that has been created and/or maintained in FirstSpirit to the customer and provides all shop functions. There is only one loose link between the two systems; they primarily work in parallel with one another. If the FirstSpirit Server is shut down because of maintenance work, for example, this has no effect on Commerce Cloud.
ContentConnect has the following technical requirements:
|
The FirstSpirit Server requires Java 8 in order to work with Commerce Cloud without problems. If you wish to use Java 7, you will need to make modifications accordingly in |
|
Chrome must be used to ensure that the preview of the sample project supplied appears correctly. You can make this setting in the SiteArchitect menu using |
This section contains information which should be noted when using the ContentConnect module.
Content assets which are created in FirstSpirit get a unique ID from FirstSpirit. If a content asset with the exact same ID is created in Commerce Cloud, this is overwritten by FirstSpirit when it is deployed.
ContentConnect consists of various components. The functionality of these components is described in the following sub-chapters.
The ContentConnect module is the main component for connecting FirstSpirit and Commerce Cloud. It is extremely important for bidirectional data exchange between the FirstSpirit Server and Commerce Cloud.
The module provides a report in both SiteArchitect and ContentCreator, showing the product information obtained from Commerce Cloud. The module determines which data is required and transfers it to the report when an editor initiates a query prompting it to do so. The data that is returned can then be used again for creating and maintaining editorial content.
If a generation is performed once the content has been created, the module combines the content in the form of two XML files. The WebDAV module then transfers the files to the Commerce Cloud storage location. Commerce Cloud reads out the data from this location and transfers it to the live state.
|
The ContentConnect module provides an API for the implementation of product-specific functions. More information is available in the accompanying Javadoc documentation. |
The editorial content is created and edited in FirstSpirit. In this case, however, it is Commerce Cloud that transfers it to the live state. This means that the content has to be made available to Commerce Cloud. For this purpose, the ContentConnect module creates one XML file for the library and one for the slot configuration as part of a deployment. These files must be transferred to Commerce Cloud along with the referenced media.
This is the task of the WebDAV module, which acts as a link between FirstSpirit and Commerce Cloud and stores the data in the Commerce Cloud storage location. Commerce Cloud reads out the data from this location.
SiteArchitect must offer the option to use JSTL tags within the template code. The JSTL module provides this. However, the module only needs to be installed on the FirstSpirit Server if JSTL has not yet been integrated on the server in any other way.
The int_firstspirit_cms cartridge provides functions for importing the editorial content created in FirstSpirit into Commerce Cloud. For this, it contains the ContentSync pipeline, which in turn has two start nodes: LIBRARY and SLOT_CONFIGURATIONS (see figure Content Sync pipeline). The editorial content is imported via LIBRARY and the slot configurations are imported via SLOT_CONFIGURATIONS accordingly. In both cases, the pipeline expects the Import File and Import Mode parameters. The pipeline should be called via job schedules (see Setting up the job schedules).
The cartridge also contains the RenderTemplate JavaScript controller. This is required to implement the mapping of Commerce Cloud render templates on FirstSpirit page templates and thereby to make it possible to create detail pages (see Product Page Template Uid, Category Page Template Uid, and Detail pages).
Various FirstSpirit and Commerce Cloud components must be installed and configured in order to use the ContentConnect functions.
The following sub-chapters explain how the components on the FirstSpirit side are installed and configured.
The ContentConnect delivery contains three modules that are added on the FirstSpirit Server. To install the modules, open the ServerManager and select → .
The main panel contains a list of all the modules installed on the FirstSpirit Server. Click , then select the contentconnect-fsm-<version number>.fsm file provided first, followed by the WebDavDeployment-<version number>.fsm and jstl.fsm files. Each time you make a selection, click to confirm it. Once installation has been successfully completed, the folders ContentConnect, WebDavDeployment, and JSTL are added to the list. Each of these must be given All permissions.
|
The JSTL module only needs to be installed on the FirstSpirit Server if JSTL has not yet been integrated on the server in any other way. |
|
After any module installation or update, the FirstSpirit Server needs to be restarted. |
The process of installing the modules must be completed by adding the Apache Commons Codec, version 1.8. This is a library that the WebDAV module uses.
For this purpose you require the commons-codec-1.8-bin.zip archive, which you can download from the following URL: http://commons.apache.org/proper/commons-codec
Extract the file anywhere within your file system and separate the commons-codec-1.8.jar file. This jar file must be added to the FirstSpirit Server: To do this, open the directory for your FirstSpirit installation, switch to the → sub-folder and copy the jar file to this location.
|
You must then restart the FirstSpirit Server. |
To use the WebDAV server with https instead of http, it is not generally necessary to perform any additional configuration work. However, a local certificate authority managed by the company is normally used for https. The certificate in question, including the entire chain up to the certificate on the WebDAV server, must be made available to the FirstSpirit Server's JVM.
|
The JVM expects public certificates of this kind to be in the form of a |
Using the command below, import the public root or intermediate certificates into a JKS file and select Yes in answer to the question whether the certificate is to be trusted. You must repeat this process for each certificate.
keytool -import -file cert1.crt -keystore truststore.jks -storepass changeit
Copy the Trust Store that is generated into the → directory of your FirstSpirit Server and add the following lines to the file → → .
wrapper.java.additional.100=-Djavax.net.ssl.trustStore=conf/truststore.jks wrapper.java.additional.101=-Djavax.net.ssl.trustStorePassword=changeit wrapper.java.additional.102=-Djavax.net.ssl.trustStoreType=JKS
|
The parameters must be activated by restarting the FirstSpirit Server. |
If the WebDAV server is expecting mutual SSL authentication, you must use the following calls to create and sign a client certificate as a first step.
openssl genrsa -out private.key 2048 openssl req -new -key private.key -out request.csr
The file request.csr is sent to the certificate authority, which responds with the file cert.crt. The private key, the public certificate, and the certificate from the certificate authority must then be collected in a Key Store to be read by the JVM.
cd firstspirit5/conf openssl pkcs12 -export -in public.crt -inkey private.key \ -out clientcert.p12 -CAfile authority.crt
If the certificate chain consists of one or more intermediate certificates, you can import them via keytool.
keytool -import -file intermediate1.crt -trustcacerts \ -keystore clientcert.p12 -storepass changeit
The Key Store can be transferred to the JVM of the FirstSpirit Server by adding the following lines to → → .
wrapper.java.additional.103=-Djavax.net.ssl.keyStore=conf/clientcert.p12 wrapper.java.additional.104=-Djavax.net.ssl.keyStorePassword=changeit wrapper.java.additional.105=-Djavax.net.ssl.keyStoreType=PKCS12
A project-specific configuration is required in order to use the ContentConnect module. It is set up using the project component, which must be added to the project being used. To add the project component, open the ServerManager and select → .
A list of all existing project components is displayed in the main panel. Click , then select the ContentConnect Project Configuration and click to confirm your selection. The project component is then added to the list in the main panel and will need to be configured (see figure Project components in the project properties). To configure the project component, select the entry in the list and click to open the associated dialog (see figure Configuration dialog for the project component).
Base URL, which is derived from the URL of the Commerce Cloud instance and the ID of the site being used:https://<SUBDOMAIN INSTANCE>.demandware.net/s/<SITE ID>Base URL field is a mandatory field.
Client ID. This is also a mandatory field, because the Client ID is a mandatory requirement in order to be able to use the Open Commerce Shop API.
|
The |
LibraryManager and SlotConfigurationManager interfaces. If you are using one of these interfaces, you must enter a password in this configuration field. Otherwise, this field can be left blank. Like the Client ID, the password to be entered is generated when the client application is registered with Commerce Cloud.
|
Up to the first nine key value pairs entered are used (Commerce Cloud will not accept more than nine refinements). The format of the values of the key value pairs matches the format Commerce Cloud expects for refinement values. Both multiple values and sets of values can be entered for a refinement:
|
|
Since a refinement is also used for category searches, two special cases need to be considered: In the first case,
In this case, there are a total of ten refinement definitions, which is not permitted. Therefore, one of the refinements from the configuration is ignored so that the product search can be filtered by a category. In the second case,
In this case, there is a duplicate definition for the |
locale parameter will not be used in storefront requests.
storefront user must be specified in this field.
storefront user is specified in this field.
|
The <CMS_INPUT_TEXT name="dw_item_id" hidden="yes" useLanguages="no"> <LANGINFOS> <LANGINFO lang="*" label=""/> </LANGINFOS> </CMS_INPUT_TEXT> |
Default Folder (Product Pages) field. The function is activated initially. If it is then deactivated, the corresponding input component is hidden in the dialog for creating a detail page. In this case, it is not possible for the editor to select or change the menu item for a newly created detail page.
|
If the check box is deactivated, it is essential for the reference name of a structure folder to be entered in the |
The mapping of page templates can be configured using this configuration field for the creation of category detail pages via the category report. The following rules apply here:
|
We recommend using separate templates for product and category detail pages. |
Editable Folder (Product Pages) check box, here it is possible to specify whether editors can change the selection made in the Default Folder (Category Pages) field. The function is activated initially. If it is then deactivated, the selection option is hidden in the dialog for creating a detail page. In this case, it is not possible for the editor to select or change the menu item for a new detail page.
|
If the check box is deactivated, it is essential for the reference name of a structure folder to be entered in the |
|
Please note that only the code from the html channel of the script is executed. |
View type priority has been provided so that you can define which image sizes you wish to incorporate, separating the information you enter with commas.large image associated with each product is identified and is used if it exists. If there is no large image, the medium image is called up, followed by the small one if the medium one does not exist.
|
As this is not a mandatory input field, it may therefore remain empty if you do not wish to define an order of priority. If this is the case, search results from a product query will be shown without an image. |
Image Service, which provides additional images for the product images that are used. If you wish to use it, you only need to enter the associated base URL at this point.
|
Specifying the |
Use Category Search? is deactivated by default. In this case, the category filter is not applied in the context of the product search. The associated dropdown list is hidden in the report. If filtering according to category is required, the checkbox must be activated.
Client ID, the Base URL and the Image Service Base URL - if available - are taken into account.
|
As some templates contain JSTL code, you must switch the template set presentation channel setting from Additionally, the conversion rule being used must contain the following line: Figure 7. html template set |
Two web components need to be added for the preview and for ContentCreator. To add a web component, open the ServerManager and select → .
Inside the main panel, various tabs are visible. Each tab contains a list of the existing web components. For the first tab page selected (Preview), click , select the ContentConnect Web Resources and FS_JSTL_WebApp, and click to confirm.
Repeat this process for ContentCreator. The web components for each of the two tab pages are then added to the list in the main panel (see figure Web components in the project properties).
The web components must be installed on an active web server and then activated. The server can be selected using the selection box.
More detailed information on how to add web components is available in the FirstSpirit Documentation for Administrators.
Some project-specific information is required for the ContentConnect module functions. This is specified in the project settings.
The template must be selected in the project properties and has to exist in the project for this purpose. If the template does not exist, start by creating it. If the template already exists, open the ServerManager and switch to → . Then click the corresponding button to select the project settings (see figure Options in the project properties). Clicking the button saves any changes that have been made.
This chapter explains how the components on the Commerce Cloud side are installed and configured.
The delivery includes the int_firstspirit_cms cartridge, which must be transferred to Commerce Cloud initially. Different methods for this are described in the Commerce Cloud documentation under Developing your storefront → Development components → Cartridges.
Next, the cartridge must be added to all sites which are to receive FirstSpirit content, as well as the business manager site. You can find relevant instructions in the Commerce Cloud documentation under Getting started → Getting started for developers → Registering your cartridge.
To import the content and slot configurations generated by FirstSpirit into Commerce Cloud, a job schedule must be created in Commerce Cloud for each site. To do this, the cartridge defines two job steps:
custom.FirstSpirit.ImportLibrary imports the content generated by FirstSpirit into Commerce Cloud
custom.FirstSpirit.ImportSlotConfigurations imports the slot configurations generated by FirstSpirit into Commerce Cloud
Both have the mandatory parameters Import File and Import Mode:
IMPEX directory.
|
The Commerce Cloud documentation contains a description of the different import modes: Administering your organization → Import and export → Import modes. |
The job schedule should contain a workflow with two parallel flows. Each flow can then call one of the two job steps above.
|
You can find general information about creating job schedules in the Commerce Cloud documentation under Administering your organization → Import and export → Importing data into and exporting data from the instance database → Job management and scheduling → Creating a new job schedule. |
In addition to the cartridge, in the metadata directory, the delivery also contains an export file for a job schedule, which can be used for reference purposes and which makes it easier to create the different job schedules.
|
As a job must be created for each site, the |
After the import, further adaptations need to be made to the job schedule. The scope of both job flows must be set to the correct site. The Import File parameter must also be adapted in both job steps so that it contains the correct path.
|
The scope of the flows as well as the |
Once the various components have been installed and configured, and the templates have been imported, a number of adaptations must be made in the project. The steps to be completed are described in the following sub-chapters.
There is some essential project-specific information that needs to be entered for the connection between FirstSpirit and Commerce Cloud (see figure Project settings). It is entered using the project settings form and must be specified within the project being used.
http or https.
Online (protected) site status. If this restriction is applied, the storefront user must be specified in FirstSpirit. Activating the checkbox displays the User and Password fields.
storefront user must be specified in this field.
storefront user is specified in this field.
Additionally, the template is used to initialize two XML collectors and a Product Manager, which are used in the other page and section templates of the project. These page and section templates define which data is to be transferred to Commerce Cloud. During the generation process, the data is collected on the basis of these definitions and the XML collectors are filled.
|
If there are project-specific requirements for the XML collectors, then these can be adapted using the methods from the Information on calling up the Product Manager is contained in the Javadoc for the |
Commerce Cloud expects all data transferred to it to be in the form of XML files. For this reason, the information written to the XML collectors during the first step of the generation is read out during the second step and written to an XML file in each case.
It must be possible to determine the file generation time for this purpose, and it must be ensured that the XML collectors have already been filled. This is the task of the XML template, which has a query that is used to evaluate the structure variable dwre_xmlGeneration during the generation process.
Query for structure variable dwre_xmlGeneration.
$CMS_IF(!#global.preview)$
$CMS_IF(!dwre_xmlGeneration.equals("true"))$
$CMS_SET(#global.stopGenerate,true)$
$CMS_END_IF$
$CMS_VALUE(xmlCollector.getXml(true))$
$CMS_END_IF$
The variable is not set to true until the second step of the generation process; this is carried out via the schedule. Otherwise, it has the value false. This means that the required XML files are not generated until this point either. Without the query, the XML collectors would be read out during the first step, which would lead to inconsistent data inventories.
|
It is possible to generate two XML files using the template. In both cases, this takes place via a collector for which a page reference based on the XML template is required. The corresponding XML collector must be selected in the form for the corresponding page. |
|
|
The folder tag generation requires a project-specific expansion of the XML template in the form of a navigation function that generates the required XML elements. Consequently, the output for this function must be expanded at a suitable point as well. The imported template contains comments indicating this requirement to expand the output.
The demo project supplied contains an example of an implementation of this kind of navigation function.
In addition to some technical format templates, the Preview Generation template is imported. With the assistance of JSTL, it is used to send a query to Commerce Cloud and request the HTML framework for the page. The framework is expanded by replacing the existing placeholders with FirstSpirit content allowing editors to see the page in the SiteArchitect preview or in ContentCreator.
The template can also be used for personalization purposes. This enables the display to be adapted when specific target groups are selected. If filtering on the basis of specific time periods is required, the code will need to be extended accordingly.
As such, the template has several tasks to complete and thus assumes a significant role within the project.
Commerce Cloud has a range of page types which in some cases have an ID in addition to a URL. For the purposes of the display in the preview or in ContentCreator, FirstSpirit must use these parameters to generate the appropriate URL for querying the corresponding page in Commerce Cloud. The Create Preview URL format template has been provided as a means of doing this.
The template expects both the type and - if it exists - the ID of the associated Commerce Cloud page. For this reason, each page template that is used must provide the following two input components:
Radio button and text field.
<CMS_INPUT_RADIOBUTTON name="pt_dwre_previewType" gridWidth="3" hFill="yes"> <ENTRIES> <ENTRY value="home"> <LANGINFOS> <LANGINFO lang="*" label="Home"/> </LANGINFOS> </ENTRY> <ENTRY value="page"> <LANGINFOS> <LANGINFO lang="*" label="Page"/> </LANGINFOS> </ENTRY> <ENTRY value="folder"> <LANGINFOS> <LANGINFO lang="*" label="Folder"/> </LANGINFOS> </ENTRY> <ENTRY value="search"> <LANGINFOS> <LANGINFO lang="*" label="Search"/> </LANGINFOS> </ENTRY> </ENTRIES> <LANGINFOS> <LANGINFO lang="*" label="Preview Page Type"/> </LANGINFOS> </CMS_INPUT_RADIOBUTTON> <CMS_INPUT_TEXT name="pt_dwre_previewPageId" hFill="yes" hidden="no"> <LANGINFOS> <LANGINFO lang="*" label="SFCC Preview Page Identifier (Page-Show:CID / Page-Search:CGID)"/> </LANGINFOS> </CMS_INPUT_TEXT>
The data entered using these components is processed further using the format templates imported initially: Default Page Header and Preview Generation. These have to be referenced via a CMS_RENDER call in the page templates being used. It is important to remember in this case that the two format templates only affect the FirstSpirit preview. Therefore, a distinction must be made to reflect this:
Referencing the format templates.
$CMS_IF(!#global.preview)$ [...] // Codepointer 1 $CMS_ELSE$ $CMS_RENDER(template:"default_page_header")$ [...] // Codepointer 2 $CMS_RENDER(template:"preview_generation")$ $CMS_END_IF$
Codepointer 1
In the part of the query that does not relate to the preview, you must define the data that is to be used to fill the XML collectors initialized in the project settings. You do this using CMS_SET calls and the add methods of the collectors. As an example, the project supplied with the module may contain the following call within the page templates:
$CMS_SET(void,ps_xmlCollector.addContentAttribute({
"name":"display-name",
"value":#global.node.getDisplayName(#global.language).toString(),
"attributes":{"xml:lang":set_xml_lang} }))$`
The call generates the tag display-name, which has the following structure in the generated XML file:
<display-name xml:lang="en">About Us</display-name>
It has the display name of the current page as a value. It is also given the language in the form of a parameter.
Codepointer 2
The placeholders from Commerce Cloud are replaced between the two CMS_RENDER calls. To do this, you must define which placeholder is to be replaced with which FirstSpirit content at this point. You also do this using CMS_SET calls and the stringToReplace and stringToInsert methods. As an example, the project supplied contains the call below for this purpose; it is located in the Homepage page template. In this case, the call is used to display the content area maintained in FirstSpirit, fs_home_cycle, instead of the placeholder. It is displayed in the preview and in ContentCreator.
$CMS_SET(void, stringToReplace.add( "<!-- CMS-CONTENT-CYCLE-START -->(?s:.)*<!-- CMS-CONTENT-CYCLE-END -->"))$ $CMS_SET(stringToInsert[stringToReplace.size-1])$ <div$CMS_VALUE(editorId(element:#global.page.body("fs_home_cycle")))$> $CMS_VALUE(#global.page.body("fs_home_cycle"))$ </div> $CMS_END_SET$
Both of these points must be carried out on a project-specific basis and can be reproduced in the sample project supplied.
|
Using the Content Integration API requires some additional points to be observed: these are outlined in chapter Page template for editorial content. |
Commerce Cloud expects all data transferred to it to be in the form of XML files. The data may only be generated once the XML collectors have been filled; otherwise, data loss can be expected. The point in time at which the files are created is controlled using the dwre_xmlGeneration structure variable, which must be created manually.
For this purpose, open the SiteStore of your project and select the → tab page before activating editing mode. Click the button and, in the dialog that opens, enter the name dwre_xmlGeneration. Click to confirm what you have entered and assign the value false in the dialog that opens at this point. Close the dialog by selecting the value .
During the second step of the generation process, the variable receives the value true via the schedule. This enables a query within the XML template to control the point in time at which the XML files to be transferred to Commerce Cloud are created.
The ContentConnect module provides a report in both SiteArchitect and ContentCreator, showing the product information obtained from Commerce Cloud. If the project component has been configured accordingly, then the search can be limited to one category and its sub-categories. The Products report figure shows the report without the category filter on the left and with the category filter on the right.
To carry out a product search, at least one of the two parameters (category, search term) must be specified. If a category is selected, then the report displays all products in this category which match the search term entered. If this term is left empty, then all products from the selected category are called up. If no specific category is selected, however, then all categories are searched for the term entered. When the category filter is inactive, then no category is used for filtering and the report behaves accordingly.
|
In Commerce Cloud, a master product has various product variants which are not displayed in the report during a standard search. However, by searching for them using their ID, they can also be found and used. |
|
In addition to the product report, the ContentConnect module supports an optional category report. The data from this report can be used in the same way as the data from the product report. |
The data from the report can be used again for creating and maintaining editorial content. Editors must be provided with the resources required to do this. This is possible in a wide variety of ways in principle. The best implementation in each case must therefore always be determined based on the prevailing requirement specific to the project.
In the sample project supplied, it is possible to reference both multiple Commerce Cloud products via an FS_LIST and a single product via a link template. If the FS_LIST is used, a new entry is added to it for each product that is selected and the product information is stored within it. By contrast, the information is stored directly in the form if the link template option is used. The implementation process involved in the two methods only differs in one respect, which is explained in chapter Form below.
The information required for the output of referenced products may differ from one application to another. General data can be used for displaying "similar products", for example, while specific variation attributes are required for what are known as "Hot Spots". Sections Output of general product information and Linking product variants below explain how information is identified and output in these two cases.
There is only one difference between the two methods of referencing Commerce Cloud products, as mentioned in the previous chapter. This chapter will therefore focus on providing an outline of how to implement the FS_LIST; it will only refer to the difference in relation to the link template at the appropriate point.
The FS_LIST is defined in the sample project within the Featured Products section template, whose form also includes the clickHandler and dropHandler buttons. Both of these buttons use the class Demandware_ProductDropHandler, which is part of the ContentConnect module and controls Commerce Cloud product transfer.
<FS_LIST name="st_productList" hFill="yes" height="400"> <DATASOURCE type="inline" useLanguages="yes"> <LABELS> <LABEL lang="*">#item.name</LABEL> </LABELS> [...] <TEMPLATES source="linktemplates"> <TEMPLATE uid="list_product_link"/> </TEMPLATES> </DATASOURCE> </FS_LIST> <FS_BUTTON name="dropHandler" icon="media:drop_zone_product" noBreak="yes" onDrop="class:DemandwareConnect_ProductDropHandler" style="link"> <DROPTYPES> <MIME type="application/x-java-serialized-object" classname="com.espirit.moddev.demandware.products.Product"/> </DROPTYPES> <PARAMS> <PARAM name="list">#field.st_productList</PARAM> <PARAM name="id">id</PARAM> <PARAM name="name">name</PARAM> </PARAMS> </FS_BUTTON> <FS_BUTTON name="clickHandler" onClick="class:DemandwareConnect_ProductDropHandler"> <LANGINFOS> <LANGINFO lang="*" label="Add product from selection"/> </LANGINFOS> <PARAMS> <PARAM name="list">#field.st_productList</PARAM> <PARAM name="id">id</PARAM> <PARAM name="name">name</PARAM> </PARAMS> </FS_BUTTON>
The two buttons are also used in the Product Hot Spot link template. However, the parameters for the buttons must be defined differently in this case:
<PARAMS> <PARAM name="id">#field.id</PARAM> <PARAM name="name">#field.name</PARAM> <PARAM name="variationAttributes">#field.variationAttributes</PARAM> </PARAMS>
The reason for this difference is that the id and name fields in the link template form are positioned in parallel to the two buttons, and are therefore addressed directly by the #field prefix expression. In the Featured Products section template, on the other hand, the buttons are arranged in parallel to the FS_LIST and the id and name fields are located in the list_product_link link template that is referenced by the FS_LIST.
The two buttons in the link template form also have the variationAttributes parameter, which addresses a hidden text field. This field is used for the persistence of specific variation attributes associated with a product. As the Featured Products section template is only used for outputting general product information, the buttons in its form do not require this parameter.
These buttons allow editors to create Commerce Cloud product referencing quickly and easily in FirstSpirit without having to leave the Client. Otherwise, they would need to determine the product information in Commerce Cloud and then enter it manually. Each FirstSpirit Client only ever shows one of the two buttons.
As mentioned previously, each of the two FirstSpirit Clients only shows one specific button. This means that whichever button is shown in each case has to be hidden in the other Client. This requirement is controlled by rules that are defined in the specified section template and in the link template.
The first query activates the clickHandler button when a Commerce Cloud product shown in the report has been copied to the clipboard.
The last two queries check whether the current editor is in ContentCreator. If the editor is in SiteArchitect, the clickHandler button is shown. Otherwise, the dropHandler button appears.
<RULES> <ON_EVENT> <SCHEDULE service="DemandwareConnect_ClipboardFilled" id="product_link_clipboard_check"> <!-- Some FS versions complain about an invalid rule definition without a parameter --> <PARAM name="dummy"> <TEXT>dummy</TEXT> </PARAM> </SCHEDULE> <DO> <PROPERTY source="clickHandler" name="EDITABLE" /> </DO> </ON_EVENT> <ON_EVENT> <WITH> <NOT> <PROPERTY source="#global" name="WEB"/> </NOT> </WITH> <DO> <PROPERTY source="clickHandler" name="VISIBLE"/> </DO> </ON_EVENT> <ON_EVENT> <WITH> <PROPERTY source="#global" name="WEB"/> </WITH> <DO> <PROPERTY source="dropHandler" name="VISIBLE"/> </DO> </ON_EVENT> </RULES>
If the variationAttributes text field appears in the form for the template that is being used, an additional dialog opens when a master product is referenced using one of the two buttons. This dialog shows all the variation attributes associated with the selected product; these attributes can be used to specify the product selection (see figure Product specification).
If the specification defines a certain product variant, the information relating to this variant is stored in the id and name fields of the link template or the FS_LIST. Otherwise, the ID and the name of the master product are accepted, and the variation attributes defined in the dialog are persisted in the form of a JSON in the hidden variationAttributes field.
The Product Manager can be used to query other product information for the purpose of displaying referenced products in the preview. The Product Manager is initialized in the project settings whose template was imported into the project during the process of configuring the project component. Depending on the application, the Product Manager can be used to determine both specific variation attributes and general product information.
This chapter outlines the concept of a "general products" list. In this case, only general information such as the name and price of a product is required. Specific attributes, by contrast, do not matter in this case.
The example below is based on the assumption that the FS_LIST described above has been used for referencing products. It is possible to reproduce this example using the Featured Products section template.
Each product that is referenced in the FS_LIST is first loaded by the Product Manager when the FOR loop is run. If the editor is in the preview, the product image, name, and price are then determined and are shown using simple getter methods.
$CMS_FOR(for_product,st_productList)$
$CMS_IF(!for_product.id.isEmpty)$
$CMS_SET(set_product,ps_productManager.loadProduct(for_product.id))$
[...]
$CMS_IF(!#global.preview)$
[...]
$CMS_ELSE$
$-- FirstSpirit Preview --$
<li>
<div class="product-tile">
<div class="product-image">
<a class="thumb-link" href="#" title="">
<img src="$CMS_VALUE(set_product.getImageUrl(set_width,set_height))$">
</a>
</div>
<div class="product-name">
<a class="name-link" href="#">
$CMS_VALUE(set_product.getName())$
</a>
<div class="product-price">
<span class="price-sales">
$CMS_VALUE(set_product.getCurrency())$
$CMS_VALUE(set_product.getPrice().format("0.00"))$
</span>
</div>
</div>
[...]
</div>
</li>
$CMS_END_IF$
$CMS_END_IF$
$CMS_END_FOR$
In contrast to the general data display described in the previous chapter, the Product Manager can be used to query even specific product information.
This chapter outlines the concept of "Hot Spots". Hot Spots are links to specific product variants. They require the variation attributes that are associated with the variant in question. General information, by contrast, does not matter in this case.
The example below is based on the assumption that the Product Hot Spot link template described above has been used for referencing a product. It is possible to reproduce the example using the template.
In the case of a product that is referenced using the link template, a link to the LinkProduct Commerce Cloud pipeline is generated first and the product ID is then transferred to the link. If the case already concerns a specific variant, the variationAttributes field remains empty. Otherwise, the Product Manager loads all the variation attributes that have been defined for product referencing purposes and are stored in the field. The Product Manager loads them one after another. The ID of each attribute (such as "Color") and its selected value (such as "yellow") are determined, and this information is used to generate a list separated by "&" characters. Finally, this list is added onto the link to the Commerce Cloud LinkProduct pipeline that was initially generated.
$CMS_IF(!#global.preview)$
$CMS_SET(set_lt_link,"$link-product:pid="+id+"$&")$
$CMS_IF(!variationAttributes.isEmpty)$
$CMS_SET(set_attributes, ps_productManager.convertVariationValuesJSON2List(variationAttributes).map(x -> x.key + "=" + x.value).toString("&"))
$CMS_SET(set_lt_link, set_lt_link + set_attributes)$
$CMS_END_IF$
$CMS_END_IF$
<a href="$CMS_VALUE(set_lt_link)$"> ... </a>
The corresponding report can be used to create detail pages for both products and categories. To use this feature, you must define the templates on which these detail pages will be based, and where they are to be integrated into the structure, in the project component.
With regard to its detail page, an object in the report can adopt one of three states:
The three cases are displayed in different ways. They are described in the following sub-chapters.
|
Since the objects in the report are not permanently updated, the display might not reflect the current status. |
Objects for which a detail page does not yet exist are identified in the report by a gray icon (see figure Creating a detail page). If a page template has been defined in the project component, the button is displayed when you hover over them.
Click on this button to open a dialog that is split into two sections and in which a detail page can be created for the corresponding object.
The top section of the dialog is the structure selection area; it is completed automatically and as such is always the same. Within the structure, the editor has the option to select the menu level at which to generate the new detail page. The corresponding input component may already have been preassigned. In this case, a structure folder will already have been defined in the configuration dialog of the project component. However, the editor is free to change this selection.
|
In some cases, the |
Unlike the structure selection area, the form area underneath is always project-specific. It shows the form for the page template specified in the project component. The rules defined in the template also apply here.
An example dialog is shown in the figure below:
Click on to generate the page reference for the detail page at the selected menu level. The corresponding page is created in a specific folder in the Page Store.
If a script has been specified in the project component, it is executed before and after the detail page is created.
|
Please note that only the code from the html channel of the script is executed. |
The following parameters are transferred to this script:
| Data type | Object name | Description |
|---|---|---|
BaseContext | context | The context in which the script is executed. |
boolean | beforeInstantiation |
|
KeyProvider | keyProvider | The object for which a detail page is being created. This is either a |
|
The Javadoc documentation supplied describes the |
Once the process to generate the detail page and the execution of the script have been completed, the new page is called up.
Objects for which a detail page already exists are identified in the report by a green icon (see figure Product with detail page). When you hover over them, the button is displayed. Click this button to call up the corresponding detail page.
Objects which have a detail page but its page reference or underlying page cannot be found are identified in the report by a red icon (see figure Broken object). When you hover over them, the button is displayed. Click on this button to open a dialog containing more information.
Transferring the content created in FirstSpirit to the Commerce Cloud storage location requires a schedule that contains at least the actions outlined below (see figure Generation schedule actions). Using the Content Integration API requires another action.
Open the ServerManager for the required schedule and select → . Add a new standard schedule here or edit one which already exists.
More information about creating a schedule is also available in the FirstSpirit Documentation for Administrators.
To deploy the content that is relevant to Commerce Cloud, it must be determined from the project first. This requires a full generation to be carried out, generating all the referenced media in the correct resolution. The full generation also generates the XML collectors initialized in the project settings and fills them on the basis of the xmlCollector calls in the templates.
For this reason, you need to start by adding a generation action to the schedule and selecting whichever name you wish for it. The following options also have to be selected in the Properties (see figure Content preparation action):
Perform FullGeneration
Clear generation directory beforehand
Generate Media in the generation directory
|
It is only possible to use the WebDAV module in conjunction with the default URL creator. It is therefore essential that you select the entry |
Additionally, you must define any Prefix for absolute paths. This is required in the last action, WebDAV deployment.
Following this, switch to the Extended tab page and select the template sets for all the languages present in the project.
Commerce Cloud expects all data that is transferred to it to be in the form of XML files. For this reason, the information determined during the full generation must be read out of the XML collectors that are generated. In this case, the information must instead be written to an XML file that has to be created each time.
For each XML collector initialized in the project settings, you therefore need to add another generation action to the schedule and give it whichever name you wish. Then, working in Properties, select the option Execute PartialGeneration for following start nodes.
Clicking the button opens a separate dialog that shows the Site Store and the Media Store. For each action, select one of the page references based on the XML template and click to confirm. The page reference is then displayed as a start node in the Properties of the generation action (see figure Partial generation).
Following this, switch to the Extended tab page and use the button to create the variable dwre_xmlGeneration. This variable must be given the value true.
|
By applying this variable and selecting the start node, you can ensure that the selected page reference is not generated until this point in time. This means that all the information required for creating the XML file will be available when this happens and it will not be possible for any gaps to appear. The XML template in the project controls the process of generating the XML file. |
Finally, the XML files generated by means of the partial generations must be transferred to Commerce Cloud. The publication process uses a script that must be added to the schedule as the final action and contains the following call:
Deployment script.
#!executable-class com.espirit.ps.custom.deploy.WebDavDeployment
Click the button to open the dialog of the same name and create the following parameters (see figure Properties):
URL specifies the host and the path on the WebDAV server. It always has the following structure:https://<SUBDOMAIN INSTANCE>.demandware.net/on/demandware.servlet/webdav/Sites/Impex/…/<PREFIX>/<SITE ID>
|
The path points to the location where the XML file in question is expected to be during the import. It must refer to an existing directory. |
|
The technical user is subject to the password conditions defined by Commerce Cloud, which require the password to be changed every quarter. The parameter value must be changed each time this is carried out. |
mediaurl. The mediaurl always has the following structure:http://<SUBDOMAIN INSTANCE>.demandware.net/on/demandware.servlet/webdav/Sites/Libraries/<SITE ID>/default/<PREFIX>
srcprefixdir. If the parameter is not defined, or no value is saved for it, the entire generation directory will be transferred.
true or false. If true is set, all the files and directories under the specified URL will be deleted before the transfer starts. If the parameter is set to false or no value at all, all the existing files and directories under the specified URL will be retained. New data will either be added or, in the case of existing data, overwritten.
|
The WebDAV deployment must not be executed in the event of an error. |
Commerce Cloud offers the option to show content for specific target groups or particular periods of time only. There are some conditions that have to be put in place if it is to be possible for editors to make personalized settings of this kind in FirstSpirit. The information below uses the sample project supplied to describe the process on the basis of restricting content to certain target groups.
Editorial content is filtered on the basis of selectable target groups that are defined in Commerce Cloud. However, Commerce Cloud does not offer the option of reading out these groups or providing them in FirstSpirit. For this reason, a data source must be created within the FirstSpirit project, and the same target groups created manually in the data source. In this case, each dataset must contain at least the ID from Commerce Cloud plus any Name that is available for selection (see figure Target groups in FirstSpirit).
You can find more information on creating a data source in the FirstSpirit online documentation.
Target groups are made available to editors by means of a page or section form. There are essentially no restrictions in this case and the display can be implemented in any way required. However, it makes sense to use one of the following input components:
The target groups are provided with a combo box in the sample project supplied:
Combo box.
<CMS_INPUT_COMBOBOX name="st_role"> <CMS_INCLUDE_OPTIONS type="database"> <LABELS> <LABEL lang="*">#item.name</LABEL> </LABELS> <TABLE>standard.roles</TABLE> </CMS_INCLUDE_OPTIONS> <LANGINFOS> <LANGINFO lang="*" label="Customer Group"/> </LANGINFOS> </CMS_INPUT_COMBOBOX>
This is located in the section templates that are being used, and references the datasets of the data source created.
Selecting a target group assigns editorial content to it. When the deployment is carried out, this assignment is transferred to Commerce Cloud, where it is mapped to the actual target group. As a result, the personalized settings are retained in the live state and are applied there.
The Multi Perspective Preview offers editors the option of assuming the perspective of one of the target groups in ContentCreator. This allows them to view a web page in a specific way and check the appearance of the personalized content they have defined. If this option were not available, editors would only be able to see the general content view and check the content in the live state.
Assuming the perspective of one of the groups requires a page template in FirstSpirit that also makes all the target groups available to the editors. For this purpose, another combo box has been provided in the sample project supplied. There are no other requirements that the page template has to meet.
MPP roles.
<CMS_INPUT_COMBOBOX name="mpp_roles"> <CMS_INCLUDE_OPTIONS type="database"> <LABELS> <LABEL lang="*">#item.name</LABEL> </LABELS> <TABLE>standard.roles</TABLE> </CMS_INCLUDE_OPTIONS> <LANGINFOS> <LANGINFO lang="*" label="Customer Group"/> </LANGINFOS> </CMS_INPUT_COMBOBOX>
Once the page template has been generated, the Multi Perspective Preview must be activated. To do this, open the ServerManager and switch to → . Then use the relevant button to select the page template that has been created as a Preview parameter (see figure Selecting the preview parameters). Clicking the button saves any changes that have been made.
If the Multi Perspective Preview is used to select a target group in ContentCreator, the page display must be adapted accordingly. However, the selected group has to be determined for this purpose first. This can be carried out using the following JSP query, for example:
Query relating to the selection of a target group.
$CMS_IF(#global.is("WEBEDIT"))$
<% if (session.getAttribute("fs.preview.mpp_roles") != null) {
String role = session.getAttribute("fs.preview.mpp_roles").toString(); %>
[...]
<% } %>
$CMS_END_IF$
|
This query may only be used up to and including FirstSpirit 5.1.
From FirstSpirit 5.2, a |
The query starts by ensuring that the active environment is ContentCreator; only then does it take effect. Its next step is to determine the selected target group, assuming the selection has not been left empty. This state must always be dealt with on a project-specific basis, as must the associated process of adapting the content that is displayed.
In the sample project supplied, the content display is controlled via CSS. In this case, the specific content starts off hidden and then becomes visible as soon as the associated target group is selected.
Display via CSS.
<style type="text/css"> .$CMS_VALUE(ps_mppCssPrefixRole)$ {display:none;} .$CMS_VALUE(ps_mppCssPrefixRole)$<%= role %> {display:block;}; </style>
In the sample project, the entire query is located in the Preview Generation format template that is integrated into the relevant page template by means of a $CMS_RENDER$ call.
If slots are being used, the parameters defined for personalization purposes must be added to the slot configuration. The code extract below shows an example of this.
Slot configuration.
$CMS_SET(set_slotConfig)$ ❶ <slot-configuration slot-id="cat-banner" ❷ context="category" context-id="$CMS_VALUE(pt_dwre_previewPageId)$" ❸ configuration-id="$CMS_VALUE("fs_slot_configuration_" + #global.section.id)$" default="true" assigned-to-site="true"> <template>slots/content/categorybanner.isml</template> <enabled-flag>true</enabled-flag> <content> <content-assets> <content-asset content-id="$CMS_VALUE(set_xml_id)$"/> </content-assets> </content> $CMS_IF(!st_role.isEmpty)$ <customer-groups> <customer-group group-id="$CMS_VALUE(st_role.getValue().id)$"/> ❹ </customer-groups> $CMS_END_IF$ </slot-configuration> $CMS_END_SET$ $CMS_IF(#global.language==#global.project.masterLanguage)$ $CMS_SET(set_xml_lang,"x-default")$ $CMS_SET(void,ps_xmlCollectorContentSlot.addXml(null,set_slotConfig.toString(),null))$ ❺ $CMS_END_IF$
|
The | |
|
Both the applicable | |
|
The ID of the selected target group is then queried. The editors select the target group using the combo box created previously. | |
|
Finally, the XML must be transferred to the relevant XML collector initialized in the project settings. This point in the process - as is also the case in the sample project - involves the collector |
In the sample project, this configuration can be found in the Banner section template.
The Content Integration API offers an alternative option for displaying personalized content.
The Content Integration API offers an additional option for displaying content from FirstSpirit in Commerce Cloud. In contrast to the procedure described previously, Velocity templates rather than slots are used in this case.
As a result, FirstSpirit adopts a different role in the design of a page. In the slot-based approach, the framework of a page is defined in Commerce Cloud; FirstSpirit simply adds content at defined points. Even if they are very straightforward, changes to the framework therefore always require amendments to the Commerce Cloud template and the slots it contains, something which editors are not able to carry out. This problem becomes even more serious in cases where changes only affect individual pages.
If the Content Integration API is used, however, FirstSpirit is able to deliver complete pages: this gives editors more freedom when designing the structure of a page. As a result, editors are able to arrange sections independently within a project-specific and page-specific scope, without the need to make any changes to templates.
Additionally, developers can use Velocity's capabilities to implement logic in templates. The Commerce Cloud Script API is also available to them for the purpose of developing their own functions. For this reason, the programming options in templates are very extensive and can be used to carry out actions such as displaying personalized content on a page.
It is possible to use the slot-based approach and the Content Integration API in parallel without any restrictions, and this is why there is the option of choosing the approach that works best for each page or page type.
This chapter describes an approach for using the Content Integration API with FirstSpirit. In addition to the content that continues to be stored in content assets, FirstSpirit generates and deploys Velocity page templates in this case. A page is displayed by means of a special JavaScript controller, which connects the content asset to the Velocity page template.
This chapter describes the Commerce Cloud extension that is required for integration. This is a JavaScript controller that is required to execute a special function but can also be extended on a project-specific basis.
Additionally, this chapter addresses the issue of caching, which must be configured correctly in the case of personalized content in particular.
|
This chapter assumes that the JavaScript controller has been stored under the |
The task of the JavaScript controller is to read out a transferred content asset and display it using a Velocity page template. This task can be divided into four basic steps:
cid
The information below describes these steps and how they are implemented.
|
The full source code of the minimal controller described in this case can be found in Appendix A, JavaScript controller. |
|
The controller implementation has been deliberately restricted to only its basic functions in order to ensure it remains simple and easy to understand. For live use, it should be extended to include elements such as a parameter validity check and robust error management. |
The JavaScript controller contains a public Show method that serves as the access point for rendering content assets and uses the dw.template.Velocity and dw.content.ContentMgr classes from the Commerce Cloud Script API. Therefore, the basic framework of the controller is as follows:
"use strict"; var contentManager = require("dw/content/ContentMgr"); ❶ var velocity = require('dw/template/Velocity'); ❷ exports.Show = function() { ❸ // ... }; exports.Show.public = true; ❹
|
Integration of | |
|
Integration of | |
|
Definition of | |
|
Enabling public access to the |
The process of reading out the content asset starts by determining the HTTP GET parameter cid, whose value is then transferred to ContentMgr in order to read out the content asset. If an editor creates a new page, Commerce Cloud is not yet aware of a content asset corresponding to it. To enable a preview of the new page to be created in FirstSpirit despite this, a temporary object that imitates an empty asset is used instead of the content asset in this case.
var contentAssetId = request.getHttpParameterMap().get("cid"); ❶ var contentAsset = contentManager.getContent(contentAssetId) ❷ || { custom: { body: "" }, template: "welcome_page.vs" }; ❸
|
Reading out the HTTP GET parameter | |
|
Querying the content asset | |
|
Definition of an empty dummy asset in the event that a content asset with the transferred ID could not be found |
An object with the name global is then defined. This object is used to provide the Velocity engine with a specialized API whose functions and properties can be used in the Velocity page template being processed. The structure and content of this object must be defined and implemented on a project-specific and page-specific basis. For example, this may involve functions that integrate various widgets under a descriptive name.
var global = {
❶
};
|
Project-specific and page-specific properties and functions |
The body property stores the content of the content asset. In the approach described here, it must always be present in the global object, in any form. As the asset content may itself contain Velocity code, it is first interpreted using the Velocity engine and the result is stored in body. When the content asset is rendered, the Velocity engine may be provided with a separate parameter object. However, it is possible to reuse global in exactly the same way.
function render(content, parameters) {
var writer = new dw.io.StringWriter();
velocity.render(content, parameters, writer)
return writer.toString();
}
// ...
global.body = render(contentAsset.custom.body, global);
Finally, the Velocity page template stored for the content asset is rendered and the result is displayed for the caller. The global object that was created previously is transferred as a parameter object.
velocity.renderTemplate(contentAsset.template, global);
Commerce Cloud offers several options for caching pages, ensuring rapid response times as a result. If, however, a page contains customer-specific or session-specific information and caching has not been configured correctly, this may quickly lead to unexpected results.
Building on the explanations in chapter JavaScript controller, the information below uses a concrete example to outline an approach that ensures an accurate result.
A page consisting of four blocks must be displayed. These blocks are made up of
These blocks offer different potential for caching.
The banner is only dependent on the customer's gender. This means that all customers can be divided into two groups: male and female. The content is identical for all customers within a group, but customers in different groups see different content. For this reason, the content can be separated for the two groups and cached over a more extensive period. Each time a page is called up, however, the customer's gender must be evaluated in order to address the correct cache.
The header contains information that is specific to each individual customer, such as his or her name. This component therefore requires caching to take place on a customer-by-customer basis. A short validity period may be maintained for the cache, as customer-specific content is required less often and for a shorter time as compared with general content.
The footer is not personalized and may, therefore, be cached for all customers and for an extended period.
The content of the content asset may itself contain Velocity code, which is why it must be viewed on a differentiated basis. However, the same information applies to it, which is why it will not be addressed in any more detail here.
The individual components have different caching requirements. It therefore makes sense to encapsulate each in a separate widget so that caching can be controlled for each one individually. As Commerce Cloud caching is based on URLs and parameters are transferred to a widget via its request URL, widget caching may be controlled via parameters. For example, it may make sense to use an isFemale parameter - containing a Boolean value - for the banner widget. This will result in two potentially valid URLs, in turn leading to two caches for the widget: one for female customers and one for male customers. An id parameter, containing the customer ID, may be defined for the header widget in exactly the same way. As a result, the content that is specific to each customer is maintained on an individual basis.
The individual widgets are then integrated by means of remote includes when the page that was initially called up is rendered. There is also the option of caching the complete result of this page; however, doing so would eliminate the settings for the individual widgets and lead to unexpected results. It is therefore important to avoid caching this response. Consequently, the requested page is reassembled each time a call is made, but the individual components are reused by means of their individual caching.
This is implemented via the JavaScript controller and the global parameter object, which the controller provides to the Velocity engine. In this example, the global object contains the parameter-free functions include.banner(), include.header(), and include.footer(), which are called up at the appropriate points in the Velocity page template. As before, it also contains the body property, which stores the content of the content asset. Within the include functions, each of the widgets is integrated into the page by means of Velocity.remoteInclude calls with appropriate parameters. The JavaScript controller which was initially called up, and which generates the global object and triggers Velocity page template rendering, must not be cached (as mentioned) in order to ensure that it is executed upon each page call and does not bypass the caching settings of the individual widgets. This is the default behavior, which is why no additional code is required.
Figure Example of caching shows the relationship between the Velocity page template, the parameter object, and widgets.
This chapter describes the FirstSpirit extensions that are required for integration.
The Velocity page template that is used is maintained in FirstSpirit and transferred to Commerce Cloud. A page template whose presentation channel has the following content in this example must be created in FirstSpirit as a starting point:
<!DOCTYPE html> <html> <body> <!-- CMS-PREVIEW-CONTENT-START --> ❶ $body ❷ <!-- CMS-PREVIEW-CONTENT-END --> ❸ </body> </html>
|
These HTML comments are required in order to generate the preview in FirstSpirit later. | |
|
The content of the content asset is integrated at this point. The |
|
On the |
Exactly one page and one page reference in each case must then be created on the basis of this new page template. The page reference at the very least should be placed on the top level of the structure in a separate folder, in order to simplify the subsequent process of transferring the Velocity page template to Commerce Cloud.
FirstSpirit generates the Velocity page template once the objects created in chapter Velocity page template have been released. For the purposes of transfer to Commerce Cloud, the schedule described in chapter Deployment schedule must be extended to include an additional WebDAV deployment. The easiest way to do this is to generate and adapt a copy of the action from chapter WebDAV deployment. The following parameters must be edited:
https://<SUBDOMAIN INSTANCE>.demandware.net/on/demandware.servlet/webdav/Sites/Dynamic/<SITE ID>
en/velocity_templates.
All other parameters can be accepted.
As this approach of using the Content Integration API continues to generate content assets, all the information in chapter Page template applies to page templates for editorial content. It is only necessary to make two specific amendments.
Firstly, it is necessary to maintain the template attribute for the content asset, as this is used in the JavaScript controller to determine the correct Velocity page template.
|
The JavaScript controller may, of course, be developed in a way that enables it to select a default Velocity page template if none is stored for the content asset. |
Additionally, a new page type must be defined for all new page templates in order to ensure that the URL generated for the preview contains the correct JavaScript controller call. Specifically, the pt_dwre_previewType must therefore be set to a new value. For the purposes of the example in this chapter, content is used.
The format template included in the delivery, Create Preview URL, needs to be extended to include one additional case so that the preview of pages which use the Content Integration API will work correctly.
The comparison value depends on the new page type that was used in the page template from chapter Page template for editorial content.
Accordingly, the called-up URL depends on the name of the controller, the method to be called, and the parameters that are required (see chapter JavaScript controller).
Therefore, in this example the new entry in the Create Preview URL template would be:
$CMS_CASE("content")$Content-Show?cid=$CMS_VALUE(pageId)$
Earlier on, it was stated that the Content Integration API offers editors more options when designing a page. In Commerce Cloud, widgets are the most ideal way of implementing visual components in cases where an editor needs to be able to place and arrange these on a page. In FirstSpirit, it is then possible to define a section template for each widget.
It is necessary to distinguish between what is a preview and what is not a preview in the presentation channel of this kind of template. The request URL of the widget is determined so that it can be used for the preview. This URL is then transferred to the include_html script, which is part of the delivery. The URL is called up in this script and the result is inserted in the generated page.
|
To enable a widget to be called up via the Internet in this way, it is necessary to allow public access to the widget. |
Where generating the content asset is concerned, only a Velocity call is generated. Which function is called up and which parameters it expects depends on the parameter object, which is defined in the JavaScript controller and is transferred to the Velocity engine when the content asset is rendered.
The Presentation channel for a widget section template listing contains a generalized example. A general function, which adopts the name of the widget and the required parameters, is used for embedding the widget.
|
When referencing a widget, it is important to pay attention to the associated Caching. |
Presentation channel for a widget section template.
$CMS_IF(#global.isPreview)$
<div $CMS_VALUE(editorId())$ >
$CMS_SET(set_includeURL, ps_dwProtocol + ps_dwInstance + ".demandware.net/on/demandware.store/")$
$CMS_SET(set_includeURL, set_includeURL + "Sites-" + ps_dwSiteId + "-Site/")$
$CMS_SET(set_includeURL, set_includeURL + #global.language.abbreviation + "/")$ ❶
$CMS_SET(set_includeURL, set_includeURL + <ACTION> + <PARAMETER>)$
$CMS_RENDER(script:"include_html", includeURL:set_includeURL.toString())$
</div>
$CMS_ELSE$
$include.widget("<ACTION>", <PARAMETER>)
$CMS_END_IF$
|
The abbreviation of the FirstSpirit language that is currently being generated is used as the language. Separate mapping to a Commerce Cloud locale may need to be implemented where necessary. |
With the Content Integration API, it is possible to show personalized content to shop visitors without the need to resort to slot configurations.
This personalization can instead be carried out using Velocity in combination with the Commerce Cloud Script API. A range of approaches and implementations may be used, depending on the specific project requirements.
One simple implementation uses a if-else branch in the content asset; this maps various personalization cases and contains only the most appropriate content as a result. The corresponding section in the body of the content asset therefore has the following appearance:
#if ($customer.isInGroup('Big Spenders'))
<!-- Content for Big Spenders -->
#elseif ($now.isBetween('2016-10-01', '2016-11-01'))
<!-- Content for all other customers during October 2016 -->
#else
<!-- Content in all other cases -->
#end
In this example, customers in the Big Spenders group are shown specific content. The same applies to all other customers in the period between 2016-10-01 and 2016-11-01. Finally, the content for other customers outside this time period is defined.
The $customer and $now functions that are used are defined in the parameter object, which is transferred to the Velocity engine in the JavaScript controller (see JavaScript controller). Its implementation uses the Commerce Cloud Script API.
|
Using the Content Integration API does not affect how the personalization is implemented for the preview in FirstSpirit. |
|
The controller implementation has been deliberately restricted to only its basic functions in order to ensure it remains simple and easy to understand. For live use, it should be extended to include elements such as a parameter validity check and robust error management. |
Full JavaScript controller.
"use strict"; var contentManager = require("dw/content/ContentMgr"); var velocity = require('dw/template/Velocity'); function render(content, parameters) { var writer = new dw.io.StringWriter(); velocity.render(content, parameters, writer) return writer.toString(); } exports.Show = function() { var contentAssetId = request.getHttpParameterMap().get("cid"); var contentAsset = contentManager.getContent(contentAssetId) || { custom: { body: "" }, template: "welcome_page.vs" }; var global = { // ... }; global.body = render(contentAsset.custom.body, global); velocity.renderTemplate(contentAsset.template, global); }; exports.Show.public = true;
ContentConnect is a product of e-Spirit AG, Dortmund, Germany.
Only a license agreed upon with e-Spirit AG is valid with respect to the user for using the module.
This document is provided for information purposes only. e-Spirit may change the contents hereof without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. e-Spirit specifically disclaims any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. The technologies, functionality, services, and processes described herein are subject to change without notice.